1. 회사명 관리

1.1 회사명 검색

o 기능 : 데이터베이스에 등록된 회사명 목록을 확인

o  URL  :  /api/sw/company?[lang={lang_code}]&[type={type_code}]& [first_char={char_value}]

- lang : C3의 해외 판매에 대비, 특정 언어의 회사명만을 검색하기 위해 사용

- type : 향후 C3 이외 다른 제품이 추가되었을 때, 특정 제품 관련 회사명만을 검색하기 위한 것으로, C3의 type_code로는 ‘1’을 사용

- first_char : 회사명이 과다해지는 상황에 대비, 특정 문자로 시작하는 회사명만을 검색하기 위해 사용

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

[

{

“com” : "{com_name}"

},

⋅⋅⋅

{

“com” : "{com_name}"

}

]

* 응답 데이터를 올림차순으로 정렬하여 전달

1.2 회사명 등록

o 기능 : 데이터베이스에 신규 회사명을 등록

o  URL  :  /api/sw/company/:com_name?[lang={lang_code}]&[type={type_code}]

* lang 및 type은 ‘회사명 검색’과 동일

o 모드 : GET

o 응답 형식 : text/plain

o 응답 데이터

200 OK

1.3 회사명 삭제

o 기능 : 데이터베이스에서 특정 회사명을 삭제

o  URL  :  /api/sw/company/:com_name?[lang={lang_code}]&[type={type_code}]

* lang 및 type은 ‘회사명 검색’과 동일

o 모드 : DELETE

o 응답 형식 : text/plain

o 응답 데이터

200 OK

2. 현장명 관리

2.1 현장명 검색

o 기능 : 데이터베이스에 등록된 현장명 목록을 확인

o  URL  :  /api/sw/site/:com_name

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

[

{

“site” : "{site_name}"

},

⋅⋅⋅

{

“site” : "{site_name}"

}

]

* 응답 데이터를 올림차순으로 정렬하여 전달

2.2 현장명 등록

o 기능 : 데이터베이스에 신규 현장명을 등록

o  URL  :  /api/sw/site/:com_name/:site_name

o 모드 : GET

o 응답 형식 : text/plain

o 응답 데이터

200 OK

2.3 현장명 삭제

o 기능 : 데이터베이스에서 특정 현장명을 삭제

o  URL  :  /api/sw/company/:com_name/:site_name

o 모드 : DELETE

o 응답 형식 : text/plain

o 응답 데이터

200 OK

3. 디바이스 관리

3.1 디바이스 등록

o 기능 : 디바이스를 등록하고 생성한 DeviceID를 전달

o  URL  :  /api/sw/device?[company={com_name}]&&[site={site_name}]

o 모드 : POST

o 전달 데이터

{

“id” :　“XXX”,

“type” : 1,

“hw” : “{CPUID}”,

“sw” : “{VersionInfo}”,

“ble” : “{BLEID}”

}

o 응답 형식 : application/json

o 응답 데이터

{

“id” : “SW2410C00001”

}

3.2 디바이스 현장 정보 확인

o 기능 : 데이터베이스에 등록된 디바이스의 현장 정보를 확인

o URL : /api/sw/device/site/:id

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

{

“com” : “{com_name}”,

“site” : “{site_name}”

}

{

“com” : null,

“site” : null

}

404 Not Found

3.3 디바이스 현장 정보 설정

o 기능 : 데이터베이스에 등록된 디바이스의 현장 정보를 설정

o URL : /api/sw/device/site/:id/:com_name/:site_name

o 모드 : GET

o 응답 형식 : text/plain

o 응답 데이터

200 OK

404 Not Found

3.4 디바이스 설정 권한 등록

o 기능 : 데이터베이스에 등록된 디바이스의 설정 권한을 등록

o URL : /api/sw/device/acl

o 모드 : POST

o 전달 데이터

[

{

“id” : “SW2410C00001”,

“acl” : “00000000“

},

⋅⋅⋅

{

“id” : “SW2410C00010”,

“acl” : “11000000“

}

]

* acl 1번째 : 검출 모드, 2번째 : 격발 중지, 3번째 : 임시 중지, 4번째 : 수동 격발

o 응답 데이터

200 OK

500 Internal Server Error

3.5 디바이스 설정 권한 확인

o 기능 : 데이터베이스에 등록된 디바이스의 설정 권한을 확인

o URL : /api/sw/device/acl/:id

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

{

“id” : “{dev_id}”,

“acl” : “{acl_code}”

}

404 Not Found

500 Internal Server Error

3.6 특정 현장 디바이스 목록 확인

o 기능 : 특정 현장명으로 등록된 디바이스 목록을 확인

o URL : /api/sw/device/list/:site?[mode={mode_value}]

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터(mode=1, default, 이름 기준)

[

{

"name": "Test",

"id": "TEST0001",

"bat": 80,

"st": 0,

"time": 777,

"gps": "10.0,20.0"

},

{

"name": "Test",

"id": "TEST0002",

"bat": 70,

"st": 1,

"time": 6070,

"gps": null

}

]

* st(0) : off, st(1) : on, time : 사용시간(초단위)

o 응답 데이터(mode=2, ID 기준)

[

{

"id": "SF_001",

"name": null,

"bat": null,

"st": 0,

"gps": null

},

{

"id": "TEST0001",

"name": "Test",

"bat": 80,

"st": 0,

"gps": "10.0,20.0"

},

⋅⋅⋅

{

"id": "TEST0002",

"name": "Test",

"bat": 70,

"st": 1,

"gps": null

}

]

o 응답 데이터(mode=3, ID 기준)

[

{

"id": "SF_001",

"bat": null,

"st": 0

},

{

"id": "TEST0001",

"bat": 80,

"st": 0

},

⋅⋅⋅

{

"id": "TEST0002",

"bat": 70,

"st": 1

}

]

o 응답 데이터(mode=4, ID 기준)

[

{

"id": "SF_001",

"name": null,

"bat": null,

"st": 0,

"time": 0,

"gps": null

},

{

"id": "TEST0001",

"name": "Test",

"bat": 80,

"st": 0,

"time": 777,

"gps": "10.0,20.0"

},

⋅⋅⋅

{

"id": "TEST0002",

"name": "Test",

"bat": 70,

"st": 1,

"time": 5974,

"gps": null

}

]

404 Not Found

500 Internal Server Error

3.7 특정 디바이스 사용시간 확인

o 기능 : 특정 기간에 대한 디바이스 사용시간을 확인

o URL : /api/sw/device/usage/id/:id?[start={date_string}]&[end={date_string}]

* date_string : yyyy-mm-dd

start	end	대상 기간
지정	지정	start <= 대상 기간 <= end
미지정		이번 달
지정	미지정	start부터 월말까지

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

[

{

"dt“: "2024-11-01",

"time": 777

},

⋅⋅⋅

{

"dt“: "2024-11-23",

"time": 6070

}

]

* time : 초 단위

3.8 특정 사용자의 사용시간 확인

o 기능 : 특정 기간에 대한 사용자의 제품 사용시간을 확인

o URL : /api/sw/device/usage/name/:name?[start={date_string}]&[end={date_string}]

* date_string : yyyy-mm-dd

start	end	대상 기간
지정	지정	start <= 대상 기간 <= end
미지정		이번 달
지정	미지정	start부터 월말까지

o 모드 : GET

o 응답 형식 : application/json

o 응답 데이터

[

{

"dt“: "2024-11-01",

"time": 777

},

⋅⋅⋅

{

"dt“: "2024-11-23",

"time": 6070

}

]

* time : 초 단위

4. 제품 출고 관리

4.1 제품 출고 통보

o 기능 : 제품 출고 목록을 받아 디바이스 관리 테이블의 Company⋅Site를 수정하고 제품 출고 목록 테이블(sw_shipment)에 기록

o  URL  :  /api/sw/shipment?[type={device_type}]

* type 1 : C3(default), 2 : D1

o 모드 : POST

o 전달 데이터

[

{

"id":"TEST0001",

"com":"TestCompany",

"site":"TestSite"

},

{

"id":"TEST0002",

"com":"TestCompany",

"site":null

},

{

"id":"TEST0003",

"com":"TestCompany",

"site":null

}

]

o 응답 데이터

200 OK

500 Internal Server Error

Error: ER_NOT_FOUND: 'TEST0001' doesn't exist.

Error: ER_DUP_ENTRY: Duplicate entry 'TEST0003' for key 'PRIMARY'

* 디바이스 관리 테이블의 Site를 `BLE출고전`으로 未설정時 오류 발생

5. 관리자 로그인 관리

5.1 Login

o 기능 : 관리자의 ID⋅PW를 받아 로그인 처리

o  URL  :  /api/sw/admin/login

o 모드 : POST

o 전달 데이터

{

"id":"{id}",

"pw":"{pw_string_encoded_in_sha256"

}

o 응답 데이터

{

"id":"TEST0001",

"com":"TestCompany",

"site":"TestSite",

"permission":1,

"token":"{token_string}

}

401 Unauthorized

404 Not Found

5.2 Logout

o 기능 : 관리자 로그아웃 처리

o  URL  :  /api/sw/admin/logout

o 모드 : GET

o 전달 데이터(HTTP 헤더)

Authorization: Bearer {token_string}

o 응답 데이터

200 OK

5.3 관리자 ID 旣등록 여부 점검

o 기능 : 신규 등록하고자 하는 ID의 旣등록 여부를 점검

o  URL  :  /api/sw/admin/check/:id

o 모드 : GET

o 응답 데이터

- 등록되지 않은 ID로, 신규 등록 가능

200 OK

- 이미 등록된 ID로, 신규 등록 불가

500 Internal Server Error

5.4 관리자 추가

o 기능 : 신규 관리자 등록

o  URL  :  /api/sw/admin/account

o 모드 : POST

o 전달 데이터

{

"id":"{id}",

"pw":"{pw_string_encoded_in_sha256",

"com":"TestCompany",

"site":"TestSite",

"permission":1

}

o 응답 데이터

200 OK

500 Internal Server Error

5.5 관리자 등록정보 확인

o 기능 : 로그인된 관리자의 등록정보를 확인

o  URL  :  /api/sw/admin/account

o 모드 : GET

o 응답 데이터

{

"id":"{id}",

"com":"TestCompany",

"site":"TestSite",

"permission":1

}

401 Unauthorized

5.6 관리자 등록정보 변경

o 기능 : 로그인된 관리자의 등록정보를 변경

o  URL  :  /api/sw/admin/account

o 모드 : PUT

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

- HTTP body

{

"id":"{id}",

"pw":"{pw_string_encoded_in_sha256",

"com":"TestCompany",

"site":"TestSite",

"permission":1

}

* pw가 null이 아니면, 패스워드만을 변경하며, pw가 null이면, com⋅site⋅permission을 변경함(未설정시 null로 변경됨)

o 응답 데이터

200 OK

500 Internal Server Error

6. 전화번호 인증 관리

6.1 인증 요청

o 기능 : 관리자 등록에 앞서 전화번호 인증 요청

o  URL  :  /api/sw/tel_auth

o 모드 : POST

o 전달 데이터

{

"tel":"{tel_no}",

"name":"{admin_name}",

"key":"{com_key}"

}

* com_key : SMS⋅이메일 등을 통해 회사에 사전 배포

o 응답 데이터

200 OK

* 서버는 응답에 앞서 인증키(6자리 랜덤 넘버)를 생성하여 SMS로 전송

500 Internal Server Error

6.2 인증 확인

o 기능 : 인증키를 전달하여 전화번호 인증 확인

o  URL  :  /api/sw/tel_auth/check

o 모드 : POST

o 전달 데이터

{

"tel":"{tel_no}",

"key":"{auth_key}"

}

o 응답 데이터

{

"com":"{company_name}“

}

401 Unauthorized

7. 회사 인증키 관리

o 관리자 권한이 ‘3’인 경우에만 호출 허용

7.1 회사 인증키 생성

o 기능 : 회사명을 전달해서 회사 인증키를 생성

o  URL  :  /api/sw/com_key

o 모드 : POST

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

- HTTP body

{

"com":"{company_name}"

}

o 응답 데이터

{

"key":"{com_key}"

}

401 Unauthorized

7.2 회사 인증키 확인

o 기능 : 특정 회사의 인증키를 확인

o  URL  :  /api/sw/com_key/:com_name

o 모드 : GET

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

o 응답 데이터

{

"key":"{com_key}“

}

401 Unauthorized

7.3 회사 인증키 삭제

o 기능 : 특정 회사의 인증키를 삭제

o  URL  :  /api/sw/com_key/:com_key

o 모드 : DELETE

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

o 응답 데이터

200 OK

401 Unauthorized

8. SMS 수신자 관리

o 관리자 권한에 따라 특정 현장(권한 1)만, 또는 특정 회사의 모든 현장(권한 2)에 대한 SMS 수신자를 관리 가능

8.1 SMS 수신자 등록

o 기능 : 신규 SMS 수신자를 등록

o  URL  :  /api/sw/sms_receiver

o 모드 : POST

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

- HTTP body

[

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

},

...

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

}

]

o 응답 데이터

200 OK

401 Unauthorized

8.2 SMS 수신자 확인

o 기능 : 특정 현장의 SMS 수신자를 확인

o  URL  :  /api/sw/sms_receiver/:com_name/:site_name

o 모드 : GET

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

o 응답 데이터

[

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

},

...

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

}

]

401 Unauthorized

8.3 SMS 수신자 삭제

o 기능 : 특정 회사의 인증키를 삭제

o  URL  :  /api/sw/sms_receiver

o 모드 : DELETE

o 전달 데이터

- HTTP header

Authorization: Bearer {token_string}

- HTTP body

[

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

},

...

{

"com":"{company_name}",

"site":"{site_name}",

"name":"{receiver_name}",

"tel":"{tel_no}"

}

]

o 응답 데이터

200 OK

401 Unauthorized